AddCollectionItem

AddCollectionItem
Header:	Collections.h		Carbon status:	Supported

Adds a new item to a collection or to replace an existing item in a collection.

OSErr AddCollectionItem (
    Collection c, 
    CollectionTag tag, 
    SInt32 id, 
    SInt32 itemSize, 
    const void *itemData
);

c: A reference to the collection you want to add the item to. The behavior of this function is undefined if you do not provide a reference to a valid collection object.
tag: The collection tag you want to associate with the new item.
id: The collection ID you want to associate with the new item.
itemSize: The size in bytes of the item’s variable-length data.
itemData: A pointer to the item’s variable-length data.

function result: A result code.

DISCUSSION

The AddCollectionItem function adds an item to the collection referenced by the c parameter. This new item contains

the collection tag specified by the tag parameter
the collection ID specified by the id parameter
the attributes specified by the default attributes of the c collection
the variable-length data specified by the itemSize and itemData parameters

This function copies the information pointed to by the itemData parameter into the new item; after calling this function, you may alter this information or free the memory pointed to by this parameter without affecting the collection.

If the c collection already contains an item with the same collection tag and collection ID as specified in the tag and id parameters, this function removes the original item and replaces it with the new one, unless the existing item is locked. If it is locked, this function returns a collectionItemLockedErr result code.

The itemSize parameter determines how many bytes of information this function copies into the new item. If you specify 0 for this parameter, or provide NULL for the itemData parameter, this function copies no information into the variable-length data of the new item, or removes the variable-length data if the item already exists.

To lock a collection item, use the functions SetCollectionItemInfo and SetIndexedCollectionItemInfo.

To replace a collection item using the item’s index (rather than the item’s tag and ID), use the ReplaceIndexedCollectionItem function.

AVAILABILITY

Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.